fix redirection links in docs #9099

ariel-anieli · 2024-11-21T11:23:56Z

Hello,

here are commits for fixing redirection links
it started from noticing that, in gen_statem, the Note didn't point to the Design Principles
noticed the same pattern in other files.

# git grep -Pn '\[OTP Design Principles\]'

lib/kernel/doc/kernel_app.md:50:manager (see [OTP Design Principles](`e:system:design_principles.md`) and
lib/kernel/doc/references/app.md:173:  information, see [OTP Design Principles](`e:system:applications.md`).
lib/kernel/doc/references/config.md:150:[OTP Design Principles](`e:system:design_principles.md`)
lib/kernel/src/application.erl:43:[OTP Design Principles](`e:system:design_principles.md`).
lib/kernel/src/application.erl:47:[OTP Design Principles](`e:system:design_principles.md`),
lib/kernel/src/error_logger.erl:38:[OTP Design Principles](`e:system:design_principles.md`) and `m:gen_event`),
lib/sasl/doc/guides/sasl_intro.md:36:section [OTP Design Principles](`e:system:index.html`) in _System
lib/sasl/doc/references/appup.md:82:[OTP Design Principles](`e:system:release_handling.md`) in _System
lib/sasl/src/release_handler.erl:29:[OTP Design Principles](`e:system:release_handling.md`) in _System
lib/sasl/src/release_handler.erl:215:[OTP Design Principles](`e:system:index.html`),
lib/stdlib/src/gen_event.erl:31:For more information, see [OTP Design Principles](`e:system:events.md`).
lib/stdlib/src/gen_event.erl:366:For more information, see [OTP Design Principles](`e:system:index.html`).
lib/stdlib/src/gen_fsm.erl:209:see [OTP Design Principles](`e:system:design_principles`).
lib/stdlib/src/gen_fsm.erl:683:[OTP Design Principles](`e:system:release_handling.md#instr`).
lib/stdlib/src/gen_statem.erl:33:see [OTP Design Principles](`e:system:statem.md`).
lib/stdlib/src/gen_statem.erl:40:> the User's Guide [OTP Design Principles](`e:system:index.html`)
lib/stdlib/src/gen_statem.erl:1742:[OTP Design Principles](`e:system:release_handling.md#instr`).
lib/stdlib/src/proc_lib.erl:26:[OTP Design Principles](`e:system:design_principles.md`). Specifically, the
system/doc/README.md:12:* [OTP Design Principles](design_principles/design_principles.md) -
system/doc/getting_started/conc_prog.md:626:  [OTP Design Principles](`e:system:design_principles.md`)).
system/doc/reference_manual/modules.md:167:[OTP Design Principles](`e:system:spec_proc.md#behaviours`).
system/doc/reference_manual/ref_man_processes.md:504:[OTP Design Principles](`e:system:design_principles.md`)
system/doc/system_principles/system_principles.md:141:[OTP Design Principles](`e:system:release_handling.md`) and the

CLAassistant · 2024-11-21T11:24:03Z

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.

Ariel Otilibili seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

github-actions · 2024-11-21T11:28:22Z

CT Test Results

4 files 162 suites 2h 16m 46s ⏱️
3 709 tests 3 421 ✅ 287 💤 1 ❌
4 363 runs 4 021 ✅ 341 💤 1 ❌

For more details on these failures, see this check.

Results for commit 952323a.

♻️ This comment has been updated with latest results.

To speed up review, make sure that you have read Contributing to Erlang/OTP and that all checks pass.

See the TESTING and DEVELOPMENT HowTo guides for details about how to run test locally.

Artifacts

// Erlang/OTP Github Action Bot

garazdawi

Many of these links are to sections within the "OTP Design Principles" Guide, so the link is correct, it is just the description that is a bit missleading. I've added some proposals to make things clearer, what do you think?

lib/kernel/doc/references/app.md

lib/sasl/doc/references/appup.md

lib/sasl/src/release_handler.erl

lib/stdlib/src/gen_event.erl

lib/stdlib/src/gen_fsm.erl

lib/stdlib/src/gen_statem.erl

ariel-anieli · 2024-11-22T09:37:02Z

Many of these links are to sections within the "OTP Design Principles" Guide, so the link is correct, it is just the description that is a bit missleading. I've added some proposals to make things clearer, what do you think?

Thanks for the feedback, @garazdawi. Maybe I should explain how I thought the links work.
Tell me, does it makes sense?

I noticed gen_statem has a note to the Design Principles
the displayed text is Design Principles, but here is the link points to the System Documentation, https://www.erlang.org/doc/system/
in fact, the Design Principles are https://www.erlang.org/doc/system/design_principles
therefore the changes;

# git diff master lib/stdlib/src/gen_statem.erl
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index 150ba7455b..875374fd7b 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -30,14 +30,14 @@ A generic state machine server process (`gen_statem`) implemented
 using this module has a standard set of interface functions
 and includes functionality for tracing and error reporting.
 It also fits into an OTP supervision tree.  For more information,
-see [OTP Design Principles](`e:system:statem.md`).
+see [OTP Design Principles](`e:system:design_principles.md`).
 
 > #### Note {: .info }
 >
 > If you are new to `gen_statem` and want an overview
 > of concepts and operation the section
 > [`gen_statem` Behaviour](`e:system:statem.md`) located in
-> the User's Guide [OTP Design Principles](`e:system:index.html`)
+> the User's Guide [OTP Design Principles](`e:system:design_principles.md`)
 > is recommended to read.  This reference manual focuses on
 > being correct and complete, which might make it hard to see
 > the forest for all the trees.
@@ -1739,7 +1739,7 @@ its internal state during a release upgrade/downgrade, that is,
 when the instruction `{update, Module, Change, ...}`,
 where `Change = {advanced, Extra}`, is specified in
 the [`appup`](`e:sasl:appup.md`) file.  For more information, see
-[OTP Design Principles](`e:system:release_handling.md#instr`).
+[OTP Design Principles](`e:system:design_principles.md#release-handling`).
 
 For an upgrade, `OldVsn` is `Vsn`, and for a downgrade, `OldVsn` is
 `{down, Vsn}`. `Vsn` is defined by the `vsn` attribute(s)

garazdawi · 2024-11-22T14:20:29Z

Maybe I should explain how I thought the links work. Tell me, does it makes sense?

I noticed gen_statem has a note to the Design Principles

the displayed text is Design Principles, but here is the link points to the System Documentation, https://www.erlang.org/doc/system/

I agree with you in the bullets above

in fact, the Design Principles are https://www.erlang.org/doc/system/design_principles

but here I think the confusion comes. There is indeed a page with a URI called "design_principles", but if you check the title of that page it is the "Overview" page. There are many pages within the Design Principles Guide and the statem page is one of them. You can see which pages are part of the Guide in the navigation bar to the left.

ariel-anieli · 2024-11-22T14:47:51Z

Gotcha, @garazdawi: Design Principles is a set of pages. I'm updating the PR along your feedback.

garazdawi · 2024-11-25T06:09:55Z

I think you may have forgotten to push your updated?

ariel-anieli · 2024-11-25T08:52:35Z

I think you may have forgotten to push your updated?

Yes, @garazdawi; bear with me, I'm pushing them by tomorrow.

garazdawi · 2024-11-25T09:01:59Z

No rush, just wanted to ping you incase it was a mistake.

ariel-anieli · 2024-11-28T15:52:39Z

No rush, just wanted to ping you incase it was a mistake.

There you are, @garazdawi; thanks for the heads up. I've just pushed a version.

ariel-anieli · 2024-12-09T13:33:28Z

Hello; any news on the PR?

garazdawi · 2024-12-09T14:19:50Z

Hello!

github actions is complaining about links in the docs being broken, so those needs to be fixed. Also the contributor license agreement needs to be signed.

Signed-off-by: Ariel Otilibili <[email protected]>

ariel-anieli · 2024-12-09T21:37:20Z

Hello!

There you are. For the license I had signed it before: here a commit I made, 37196c2.

garazdawi · 2024-12-10T09:18:31Z

There you are.

Thanks!

For the license I had signed it before: here a commit I made, 37196c2.

Ah, the tool does not discover it as you don't have that email address added to your github account.

All is good then. Thanks for you contribution!

ariel-anieli · 2024-12-10T10:15:41Z

There you are.

Thanks!

For the license I had signed it before: here a commit I made, 37196c2.

Ah, the tool does not discover it as you don't have that email address added to your github account.

Thanks for the heads up.

All is good then. Thanks for you contribution!

🙂 Great!

garazdawi reviewed Nov 22, 2024

View reviewed changes

IngelaAndin added the team:VM Assigned to OTP team VM label Nov 25, 2024

garazdawi self-assigned this Nov 25, 2024

ariel-anieli force-pushed the typo-gen-statem branch from c8c3772 to 232fcc7 Compare November 28, 2024 15:51

ariel-anieli requested a review from garazdawi November 28, 2024 15:52

ariel-anieli force-pushed the typo-gen-statem branch from 232fcc7 to e89273c Compare December 9, 2024 13:33

ariel-anieli added 3 commits December 9, 2024 21:58

lib/stdlib: fix redirection links in docs

f25886e

Signed-off-by: Ariel Otilibili <[email protected]>

lib/sasl: fix redirection links in docs

3c82d6c

Signed-off-by: Ariel Otilibili <[email protected]>

system/doc: fix redirection links in docs

952323a

Signed-off-by: Ariel Otilibili <[email protected]>

ariel-anieli force-pushed the typo-gen-statem branch from e89273c to 952323a Compare December 9, 2024 21:02

garazdawi approved these changes Dec 10, 2024

View reviewed changes

garazdawi merged commit 3749221 into erlang:master Dec 10, 2024
23 of 26 checks passed

ariel-anieli deleted the typo-gen-statem branch December 10, 2024 10:18

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix redirection links in docs #9099

fix redirection links in docs #9099

ariel-anieli commented Nov 21, 2024 •

edited

Loading

CLAassistant commented Nov 21, 2024

github-actions bot commented Nov 21, 2024 •

edited

Loading

garazdawi left a comment

ariel-anieli commented Nov 22, 2024 •

edited

Loading

garazdawi commented Nov 22, 2024

ariel-anieli commented Nov 22, 2024

garazdawi commented Nov 25, 2024

ariel-anieli commented Nov 25, 2024

garazdawi commented Nov 25, 2024

ariel-anieli commented Nov 28, 2024

ariel-anieli commented Dec 9, 2024

garazdawi commented Dec 9, 2024

ariel-anieli commented Dec 9, 2024

garazdawi commented Dec 10, 2024

ariel-anieli commented Dec 10, 2024

fix redirection links in docs #9099

fix redirection links in docs #9099

Conversation

ariel-anieli commented Nov 21, 2024 • edited Loading

CLAassistant commented Nov 21, 2024

github-actions bot commented Nov 21, 2024 • edited Loading

CT Test Results

Artifacts

garazdawi left a comment

Choose a reason for hiding this comment

ariel-anieli commented Nov 22, 2024 • edited Loading

garazdawi commented Nov 22, 2024

ariel-anieli commented Nov 22, 2024

garazdawi commented Nov 25, 2024

ariel-anieli commented Nov 25, 2024

garazdawi commented Nov 25, 2024

ariel-anieli commented Nov 28, 2024

ariel-anieli commented Dec 9, 2024

garazdawi commented Dec 9, 2024

ariel-anieli commented Dec 9, 2024

garazdawi commented Dec 10, 2024

ariel-anieli commented Dec 10, 2024

ariel-anieli commented Nov 21, 2024 •

edited

Loading

github-actions bot commented Nov 21, 2024 •

edited

Loading

ariel-anieli commented Nov 22, 2024 •

edited

Loading